HAL RNG migration: List of applicable concepts ¶

This section provides information about the HAL RNG applicable architecture concepts.

Concepts for RNG ¶

Concept	Description
Separation of initialization and configuration functions	The initialization has been split into separate init and config functions: `HAL_RNG_Init`: initializes the handle and links it to a RNG instance. `HAL_RNG_SetConfig`: sets the configuration for the RNG peripheral.
Removal and conversion of init structure to configuration structure	The init structure has been removed and moved into `hal_rng_config_t` configuration structure.
Renaming of the handle structure	The handle structure has been renamed to `hal_rng_handle_t`.
Remove MspInit and MspDeInit callbacks	`HAL_RNG_MspInit` and `HAL_RNG_MspDeInit` are no longer available and have been replaced by a user sequence to initialize and configure the RNG.
Unitary configuration APIs	New APIs are available to get and set RNG features.
Individual callback registration APIs replace global register and unregister functions	The callback registration is handled by specific functions for each RNG event. These functions are used to register callback functions for different RNG events.
HAL implementation with LL inline functions	HAL RNG APIs now rely on LL APIs rather than performing direct register access.
Define statements and enumerations redirected to LL equivalents	HAL RNG define statements and enumerations are based on LL define statements.
Removal of hardware-related macros in HAL2	All hardware macros have been removed from the HAL RNG driver, and equivalent services are ensured through the LL APIs.
Revised and optimized HAL state machine	The RNG state machine has been reworked to ensure transitions of the peripheral functional states.
Revised and optimized HAL API status returns	The HAL RNG functions were updated to return: `HAL_INVALID_PARAM`: in case of a NULL p_config structure pointer. `HAL_ERROR`: in case of an error. `HAL_TIMEOUT`: in case of a user timeout. `HAL_BUSY`: in case of an ongoing process. `HAL_OK`: in case of a successfully completed operation.
Revised and optimized HAL error management	The HAL error handling mechanisms have been redesigned to improve the detection, reporting, and handling of errors. This provides more detailed and consistent error information.
Replaced TypeDef suffix with _t in type names	All TypeDef parts of the HAL RNG driver have been removed and replaced by `_t`.
Replaced multi-line macros with inline functions	For the HAL RNG driver, large macros have been replaced by inline functions to maintain code consistency, improve readability, and benefit from compiler optimization. Inline functions also offer better support for debugging and strict type management, reducing the risk of errors.
Replaced nonmodifiable pointers with const keywords	Const keywords have been added to non-modifiable pointers to ensure that either the pointer itself or the data it points to cannot be modified. This enhances code safety and readability, prevents unintended modifications, and renders code more robust and maintainable.
Assertion implementation and usage in HAL1	The parameters and state are checked using `ASSERT_DBG_STATE` and `ASSERT_DBG_PARAM` macro.
Merge HAL extension files with common ones and remove the EX prefix from APIs.	Only one HAL RNG header file remains and all macros, define statements, and functions from `hal_rng_ex.h` have been moved to `hal_rng.h`.
Replace Finite Parameter Defines (Including PPP Instances) with Enum Types at HAL Levels.	Finite parameters (including RNG instances) have been converted into enumerated types (enums) at HAL level. This improves code readability, maintainability, and type safety.
Add HAL_PPP Prefix to All HAL Peripheral APIs (Defines, Macros, Types, and Functions).	All HAL RNG functions start with `HAL_RNG`. All HAL RNG enum and struct start with `hal_rng`.

Other HAL RNG Changes ¶

Concept	Consideration
Rework process APIs concept to support all RNG IP version.	The design philosophy is to provide a set of APIs that allow the user to generate random numbers in both polling and interrupt modes: Polling mode: `HAL_RNG_GenerateRandomNumber()`: generates N random 32-bit words. The generation process is bounded by a user-defined timeout. Interrupt mode: `HAL_RNG_GenerateRandomNumber_IT()`: generates N random 32-bit words using interrupts. `HAL_RNG_IRQHandler()`: handles RNG-related interrupts and invokes `HAL_RNG_GenerationCpltCallback()` when the generation is complete.
Provide ready-to-use APIs that embed predefined configurations.	Three functions are provided: Candidate German BSI standard configuration function: `HAL_RNG_SetCandidateGermanBSIConfig()`. NIST standard configuration function: `HAL_RNG_SetCertifiedNISTConfig()` flagged with `RNG_CERT_NIST`. Candidate NIST configuration function: `HAL_RNG_SetCandidateNISTConfig()`.
Remove recovery mechanism from get random number API.	It’s up to user to recover any seed error through the `HAL_RNG_RecoverSeedError()` as: Recovery is not always guaranteed. This approach provides flexibility in how the recovery mechanism is implemented within the application. The recovery function can be invoked from within the error callback, enabling implementations based on static timing rather than SysTick. Once recovery is successful, the user may call the polling or interrupt-based APIs again to restart random number generation

Concept

Consideration

Rework process APIs concept to support all RNG IP version.

The design philosophy is to provide a set of APIs that allow the user to generate random numbers in both polling and interrupt modes:

Polling mode:

HAL_RNG_GenerateRandomNumber(): generates N random 32-bit words. The generation process is bounded by a user-defined timeout.
Interrupt mode:
- HAL_RNG_GenerateRandomNumber_IT(): generates N random 32-bit words using interrupts.
- HAL_RNG_IRQHandler(): handles RNG-related interrupts and invokes HAL_RNG_GenerationCpltCallback() when the generation is complete.

Provide ready-to-use APIs that embed predefined configurations.

Three functions are provided:

Candidate German BSI standard configuration function: HAL_RNG_SetCandidateGermanBSIConfig().
NIST standard configuration function: HAL_RNG_SetCertifiedNISTConfig() flagged with RNG_CERT_NIST.
Candidate NIST configuration function: HAL_RNG_SetCandidateNISTConfig().

Remove recovery mechanism from get random number API.

It’s up to user to recover any seed error through the HAL_RNG_RecoverSeedError() as:

Recovery is not always guaranteed.
This approach provides flexibility in how the recovery mechanism is implemented within the application.
The recovery function can be invoked from within the error callback, enabling implementations based on static timing rather than SysTick.
Once recovery is successful, the user may call the polling or interrupt-based APIs again to restart random number generation